Repository navigation
trains: prescribed-signal inverse EPG and Busse train design in a C++ kernel - #56
Merged
Merged
Conversation
… kernel blochsim.trains designs refocusing trains from the echo signal they are to give: prescribed_flips inverts the phase graph of a CPMG train echo by echo, busse_flips builds the Busse variable-flip-angle trains on it, effective_te gives the contrast-equivalent echo time, and busse_centre_echo places the centre echo for one by trying every centre in a batch. The kernel (_trains_cpu) is double precision, host only, threaded over the trains of a batch, and takes NumPy arrays. It shares the real-subspace shift and rotation with the float simulation kernel through _real_subspace.hpp. Co-Authored-By: Claude Opus 5.5 <[email protected]>
import blochsim imports blochsim.trains alone, so a train is designed at NumPy's import cost; everything built on PyTorch is imported the first time it is asked for. The CPU kernels' worker pool is tied to the process that created it, so a child forked after a threaded call does not wait on workers it does not have. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The lazy import held a lock of its own while importing subpackages, and a missing optional module asked for by 'from blochsim import _gpu' took it too: one thread using blochsim.Simulator and another importing blochsim.estimators waited on each other. The lock is gone, so the import system sees every cycle, and a private name that is no submodule is an AttributeError without loading anything. prescribed_flips refuses amplitudes and first angles that are not finite, and in the kernel an echo that is not a number leaves every later angle not a number, where it left zeros. busse_flips broadcasts centre_echo and startup_echoes into the batch shape. The MINPACK fallback and the no-centre error are tested. The changelog entries are once. Co-Authored-By: Claude Opus 5.5 <[email protected]>
mcencini
marked this pull request as ready for review
November 11, 2026 01:30
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
blochsim.trainsis new: refocusing trains designed from the echo signal they are to give. It replaces the NumPy EPG that pypulseqpp grew for this (pypulseqpp_busse.py,_pd.py,_fse_contrast.py), so the phase graph lives in one package.prescribed_flipsbusse_flipsbusse_centre_echoeffective_teDesign
_trains_cpu.cppis a third CPU extension: double precision, host only, torch-free, threaded over the trains of a batch on the existingWorkerPool. It has two entry points,inverseandforward._real_subspace.hpp._epg_cpu.cppuses them atfloat(shift_real,simulate_real_range), the new kernel atdouble. The CPMG train is the second real subspace (transverse along the pulse axis), which differs from the engine's only in the sign of the shift's conjugate coupling.import blochsimis lazy (second commit; no lock of its own, so the import system sees every cycle between threads, and a private name that is not a submodule is anAttributeErrorwithout loading anything). It importsblochsim.trainsalone; everything built on PyTorch loads on first use (attribute,from blochsim import ..., submodule,dir,__all__). Without this, a consumer designing a train would pay forimport torch(1.6-2.2 s measured here,import blochsim2.5-3.5 s) to run a 30 ms solve. The commit is separable: reverting it leavesblochsim.trainsworking, at torch's import cost.WorkerPoolis tied to the process that created it. A child forked after a threaded kernel call used to wait forever on workers it does not have; it now starts its own pool.Measured
Laptop (20 threads, load average about 30 during the runs, so absolute numbers are pessimistic).
make_pd_schedule, 26-166 pulses), through pypulseqppimport blochsim.trainsafter NumPyAgreement with the NumPy implementation:
main(FSE, 20 000 voxels, 128 echoes, 10 and 32 states).Tests
tests/trains/(94 tests): echoes checked by isochromat summation written intests/utils/isochromats.py; closed forms (180 degree train, first echo); the pseudo-steady-state amplitude against SciPy's Legendre function; the 106-pulse Busse Figure 1 train against a frozen reconstruction; centre search against a one-at-a-time loop; batch equals alone, bit for bit; torch-free import and lazy-load routes in subprocesses; pool afterfork.pytest tests -n 6, CPU build with host kernels: 1644 passed, 327 skipped, 5 failed. Four were the new docstrings not followingtest_docstring_defaults(fixed, now pass). One,test_an_image_quality_design_fits_in_its_budget, is a 3 s wall-clock budget that failed under load and passes alone.ruff checkandruff format --checkclean onsrc,tests,scripts.Not verified here: the MSVC, clang (macOS) and musl builds of the new extension (this PR's Wheels run is the first); a docs build; the CUDA wheels (unchanged sources, but they rebuild).
After review
blochsim.Simulatorwhile another importedblochsim.estimatorson an install without_gpu. The lock is removed; three two-thread tests with a timeout cover it, and the reviewer's probe passes 3 of 3.prescribed_flipsraises on non-finite amplitudes or first angles; in the kernel a NaN echo now leaves NaN angles after it instead of zeros.busse_flipsbroadcastscentre_echoandstartup_echoesinto the batch shape.tests/trainsis now 104 tests.Release
pypulseqpp's follow-up PR needs this on PyPI as 0.0.18. Tag
v0.0.18onmainafter merge (Tagworkflow from the Actions page, orgit tag v0.0.18 && git push origin v0.0.18).wheels.ymlthen builds the sdist, the CPU wheels andblochsim-cuda12/blochsim-cuda13, and publishes all three projects to PyPI through trusted publishing (environmentspypi,pypi-cuda12,pypi-cuda13). The CUDA builds are PyPI projects, not GitHub release assets.scripts/check_wheel.pynow expects three CPU kernels.🤖 Generated with Claude Code